/*
    * Copyright (C) 2012 The Guava Authors
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.apache.org/licenses/LICENSE-2.0
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package com.google.common.io;
  
  import static com.google.common.base.Preconditions.checkNotNull;
  
  import com.google.common.annotations.Beta;
  import com.google.common.annotations.VisibleForTesting;
  import com.google.common.base.Throwables;
  
  import java.io.Closeable;
  import java.io.IOException;
  import java.lang.reflect.Method;
  import java.util.ArrayDeque;
  import java.util.Deque;
  import java.util.logging.Level;
  
  import javax.annotation.Nullable;
  
  /**
   * A {@link Closeable} that collects {@code Closeable} resources and closes them all when it is
   * {@linkplain #close closed}. This is intended to approximately emulate the behavior of Java 7's
   * <a href="http://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html">
   * try-with-resources</a> statement in JDK6-compatible code. Running on Java 7, code using this
   * should be approximately equivalent in behavior to the same code written with try-with-resources.
   * Running on Java 6, exceptions that cannot be thrown must be logged rather than being added to the
   * thrown exception as a suppressed exception.
   *
   * <p>This class is intended to be used in the following pattern:
   *
   * <pre>   {@code
   *   Closer closer = Closer.create();
   *   try {
   *     InputStream in = closer.register(openInputStream());
   *     OutputStream out = closer.register(openOutputStream());
   *     // do stuff
   *   } catch (Throwable e) {
   *     // ensure that any checked exception types other than IOException that could be thrown are
   *     // provided here, e.g. throw closer.rethrow(e, CheckedException.class);
   *     throw closer.rethrow(e);
   *   } finally {
   *     closer.close();
   *   }}</pre>
   *
   * <p>Note that this try-catch-finally block is not equivalent to a try-catch-finally block using
   * try-with-resources. To get the equivalent of that, you must wrap the above code in <i>another</i>
   * try block in order to catch any exception that may be thrown (including from the call to
   * {@code close()}).
   *
   * <p>This pattern ensures the following:
   *
   * <ul>
   *   <li>Each {@code Closeable} resource that is successfully registered will be closed later.</li>
   *   <li>If a {@code Throwable} is thrown in the try block, no exceptions that occur when attempting
   *   to close resources will be thrown from the finally block. The throwable from the try block will
   *   be thrown.</li>
   *   <li>If no exceptions or errors were thrown in the try block, the <i>first</i> exception thrown
   *   by an attempt to close a resource will be thrown.</li>
   *   <li>Any exception caught when attempting to close a resource that is <i>not</i> thrown
   *   (because another exception is already being thrown) is <i>suppressed</i>.</li>
   * </ul>
   *
   * <p>An exception that is suppressed is not thrown. The method of suppression used depends on the
   * version of Java the code is running on:
   *
   * <ul>
   *   <li><b>Java 7+:</b> Exceptions are suppressed by adding them to the exception that <i>will</i>
   *   be thrown using {@code Throwable.addSuppressed(Throwable)}.</li>
   *   <li><b>Java 6:</b> Exceptions are suppressed by logging them instead.</li>
   * </ul>
   *
   * @author Colin Decker
   * @since 14.0
   */
  // Coffee's for {@link Closer closers} only.
  @Beta
  public final class Closer implements Closeable {
  
    /**
     * The suppressor implementation to use for the current Java version.
     */
    private static final Suppressor SUPPRESSOR = SuppressingSuppressor.isAvailable()
        ? SuppressingSuppressor.INSTANCE
        : LoggingSuppressor.INSTANCE;
  
   /**
    * Creates a new {@link Closer}.
    */
   public static Closer create() {
     return new Closer(SUPPRESSOR);
   }
 
   @VisibleForTesting final Suppressor suppressor;
 
   // only need space for 2 elements in most cases, so try to use the smallest array possible
   private final Deque<Closeable> stack = new ArrayDeque<Closeable>(4);
   private Throwable thrown;
 
   @VisibleForTesting Closer(Suppressor suppressor) {
     this.suppressor = checkNotNull(suppressor); // checkNotNull to satisfy null tests
   }
 
   /**
    * Registers the given {@code closeable} to be closed when this {@code Closer} is
    * {@linkplain #close closed}.
    *
    * @return the given {@code closeable}
    */
   // close. this word no longer has any meaning to me.
   public <C extends Closeable> C register(@Nullable C closeable) {
     if (closeable != null) {
       stack.addFirst(closeable);
     }
 
     return closeable;
   }
 
   /**
    * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
    * {@code IOException}, {@code RuntimeException} or {@code Error}. Otherwise, it will be rethrown
    * wrapped in a {@code RuntimeException}. <b>Note:</b> Be sure to declare all of the checked
    * exception types your try block can throw when calling an overload of this method so as to avoid
    * losing the original exception type.
    *
    * <p>This method always throws, and as such should be called as
    * {@code throw closer.rethrow(e);} to ensure the compiler knows that it will throw.
    *
    * @return this method does not return; it always throws
    * @throws IOException when the given throwable is an IOException
    */
   public RuntimeException rethrow(Throwable e) throws IOException {
     checkNotNull(e);
     thrown = e;
     Throwables.propagateIfPossible(e, IOException.class);
     throw new RuntimeException(e);
   }
 
   /**
    * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
    * {@code IOException}, {@code RuntimeException}, {@code Error} or a checked exception of the
    * given type. Otherwise, it will be rethrown wrapped in a {@code RuntimeException}. <b>Note:</b>
    * Be sure to declare all of the checked exception types your try block can throw when calling an
    * overload of this method so as to avoid losing the original exception type.
    *
    * <p>This method always throws, and as such should be called as
    * {@code throw closer.rethrow(e, ...);} to ensure the compiler knows that it will throw.
    *
    * @return this method does not return; it always throws
    * @throws IOException when the given throwable is an IOException
    * @throws X when the given throwable is of the declared type X
    */
   public <X extends Exception> RuntimeException rethrow(Throwable e,
       Class<X> declaredType) throws IOException, X {
     checkNotNull(e);
     thrown = e;
     Throwables.propagateIfPossible(e, IOException.class);
     Throwables.propagateIfPossible(e, declaredType);
     throw new RuntimeException(e);
   }
 
   /**
    * Stores the given throwable and rethrows it. It will be rethrown as is if it is an
    * {@code IOException}, {@code RuntimeException}, {@code Error} or a checked exception of either
    * of the given types. Otherwise, it will be rethrown wrapped in a {@code RuntimeException}.
    * <b>Note:</b> Be sure to declare all of the checked exception types your try block can throw
    * when calling an overload of this method so as to avoid losing the original exception type.
    *
    * <p>This method always throws, and as such should be called as
    * {@code throw closer.rethrow(e, ...);} to ensure the compiler knows that it will throw.
    *
    * @return this method does not return; it always throws
    * @throws IOException when the given throwable is an IOException
    * @throws X1 when the given throwable is of the declared type X1
    * @throws X2 when the given throwable is of the declared type X2
    */
   public <X1 extends Exception, X2 extends Exception> RuntimeException rethrow(
       Throwable e, Class<X1> declaredType1, Class<X2> declaredType2) throws IOException, X1, X2 {
     checkNotNull(e);
     thrown = e;
     Throwables.propagateIfPossible(e, IOException.class);
     Throwables.propagateIfPossible(e, declaredType1, declaredType2);
     throw new RuntimeException(e);
   }
 
   /**
    * Closes all {@code Closeable} instances that have been added to this {@code Closer}. If an
    * exception was thrown in the try block and passed to one of the {@code exceptionThrown} methods,
    * any exceptions thrown when attempting to close a closeable will be suppressed. Otherwise, the
    * <i>first</i> exception to be thrown from an attempt to close a closeable will be thrown and any
    * additional exceptions that are thrown after that will be suppressed.
    */
   @Override
   public void close() throws IOException {
     Throwable throwable = thrown;
 
     // close closeables in LIFO order
     while (!stack.isEmpty()) {
       Closeable closeable = stack.removeFirst();
       try {
         closeable.close();
       } catch (Throwable e) {
         if (throwable == null) {
           throwable = e;
         } else {
           suppressor.suppress(closeable, throwable, e);
         }
       }
     }
 
     if (thrown == null && throwable != null) {
       Throwables.propagateIfPossible(throwable, IOException.class);
       throw new AssertionError(throwable); // not possible
     }
   }
 
   /**
    * Suppression strategy interface.
    */
   @VisibleForTesting interface Suppressor {
     /**
      * Suppresses the given exception ({@code suppressed}) which was thrown when attempting to close
      * the given closeable. {@code thrown} is the exception that is actually being thrown from the
      * method. Implementations of this method should not throw under any circumstances.
      */
     void suppress(Closeable closeable, Throwable thrown, Throwable suppressed);
   }
 
   /**
    * Suppresses exceptions by logging them.
    */
   @VisibleForTesting static final class LoggingSuppressor implements Suppressor {
 
     static final LoggingSuppressor INSTANCE = new LoggingSuppressor();
 
     @Override
     public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) {
       // log to the same place as Closeables
       Closeables.logger.log(Level.WARNING,
           "Suppressing exception thrown when closing " + closeable, suppressed);
     }
   }
 
   /**
    * Suppresses exceptions by adding them to the exception that will be thrown using JDK7's
    * addSuppressed(Throwable) mechanism.
    */
   @VisibleForTesting static final class SuppressingSuppressor implements Suppressor {
 
     static final SuppressingSuppressor INSTANCE = new SuppressingSuppressor();
 
     static boolean isAvailable() {
       return addSuppressed != null;
     }
 
     static final Method addSuppressed = getAddSuppressed();
 
     private static Method getAddSuppressed() {
       try {
         return Throwable.class.getMethod("addSuppressed", Throwable.class);
       } catch (Throwable e) {
         return null;
       }
     }
 
     @Override
     public void suppress(Closeable closeable, Throwable thrown, Throwable suppressed) {
       // ensure no exceptions from addSuppressed
       if (thrown == suppressed) {
         return;
       }
       try {
         addSuppressed.invoke(thrown, suppressed);
       } catch (Throwable e) {
         // if, somehow, IllegalAccessException or another exception is thrown, fall back to logging
         LoggingSuppressor.INSTANCE.suppress(closeable, thrown, suppressed);
       }
     }
   }
 }